home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Mac Game Programming Gurus / TricksOfTheMacGameProgrammingGurus.iso / CodeWarrior Lite / Metrowerks C⁄C++ Lite / Headers / Universal Headers 2.0.1f / Translation.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-03-22  |  12.0 KB  |  309 lines  |  [TEXT/MMCC]
  1. /*
  2.      File:        Translation.h
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Package:    Universal Interfaces 2.0 in “MPW Latest” on ETO #17
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. */
  19.  
  20. #ifndef __TRANSLATION__
  21. #define __TRANSLATION__
  22.  
  23.  
  24. #ifndef __TYPES__
  25. #include <Types.h>
  26. #endif
  27. /*    #include <ConditionalMacros.h>                                */
  28.  
  29. #ifndef __FILES__
  30. #include <Files.h>
  31. #endif
  32. /*    #include <MixedMode.h>                                        */
  33. /*    #include <OSUtils.h>                                        */
  34. /*        #include <Memory.h>                                        */
  35.  
  36. #ifndef __COMPONENTS__
  37. #include <Components.h>
  38. #endif
  39.  
  40. #ifndef __TRANSLATIONEXTENSIONS__
  41. #include <TranslationExtensions.h>
  42. #endif
  43. /*    #include <Quickdraw.h>                                        */
  44. /*        #include <QuickdrawText.h>                                */
  45.  
  46. #ifdef __cplusplus
  47. extern "C" {
  48. #endif
  49.  
  50. #if PRAGMA_ALIGN_SUPPORTED
  51. #pragma options align=mac68k
  52. #endif
  53.  
  54. #if PRAGMA_IMPORT_SUPPORTED
  55. #pragma import on
  56. #endif
  57.  
  58. typedef short DocOpenMethod;
  59.  
  60.  
  61. enum {
  62.     domCannot,
  63.     domNative,
  64.     domTranslateFirst,
  65.     domWildcard
  66. };
  67.  
  68. /* 0L terminated array of OSTypes, or FileTypes*/
  69. typedef OSType TypesBlock[64];
  70.  
  71. typedef OSType *TypesBlockPtr;
  72.  
  73. /* Progress dialog resource ID*/
  74.  
  75. enum {
  76.     kTranslationScrapProgressDialogID = -16555
  77. };
  78.  
  79. /* block of data that describes how to translate*/
  80. struct FileTranslationSpec {
  81.     OSType                            componentSignature;
  82.     const void                        *translationSystemInfo;
  83.     FileTypeSpec                    src;
  84.     FileTypeSpec                    dst;
  85. };
  86. typedef struct FileTranslationSpec FileTranslationSpec;
  87.  
  88. typedef FileTranslationSpec *FileTranslationSpecArrayPtr;
  89.  
  90. /*****************************************************************************************
  91. * 
  92. *   GetFileTypesThatAppCanNativelyOpen
  93. * 
  94. *  This routine returns a list of all FileTypes that an application can open by itself
  95. * 
  96. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  97. *             appSignature        signature (creator) of application
  98. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  99. * 
  100. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  101. */
  102. extern pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  103.  TWOWORDINLINE(0x701C, 0xABFC);
  104. /*****************************************************************************************
  105. * 
  106. *  ExtendFileTypeList
  107. * 
  108. *  This routine makes a new list of file types that can be translated into a type in the given list
  109. *  Used by StandardFile
  110. * 
  111. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  112. *             numberOriginalTypes        number of file types in orgTypeList
  113. *              extendedTypeList        pointer to a buffer to be filled with file types
  114. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  115. * 
  116. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  117. *             numberExtendedTypes        number of file types put in extendedTypeList
  118. */
  119. extern pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  120.  TWOWORDINLINE(0x7009, 0xABFC);
  121. /*****************************************************************************************
  122. * 
  123. * 
  124. *  This routine checks if a file can be opened by a particular application.
  125. *  If so, it returns if it needs to be translated first, and if so then how.
  126. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  127. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  128. * 
  129. *  Enter:    targetDocument        document to check if it can be opened
  130. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  131. *             appSignature        signature (creator) of application to open doc
  132. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  133. *             onlyNative            whether to consider if document can be translated before opening
  134. *             howToOpen            pointer to buffer in which to put how the document can be opened
  135. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  136. * 
  137. *  Exit:    howToOpen            whether file needs to be translated to be read
  138. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  139. *             returns                noErr, noPrefAppErr
  140. */
  141. extern pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  142.  TWOWORDINLINE(0x701E, 0xABFC);
  143. /*****************************************************************************************
  144. * 
  145. *  GetFileTranslationPaths
  146. * 
  147. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  148. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  149. * 
  150. *  Enter:    srcDoc            source file or NULL for all matches
  151. *             dstDoc            destination FileType or NULL for all matches
  152. *             maxResultCount
  153. *             resultBuffer
  154. *  Exit:    number of paths
  155. */
  156. extern pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  157.  TWOWORDINLINE(0x7038, 0xABFC);
  158. /*****************************************************************************************
  159. * 
  160. *  GetPathFromTranslationDialog
  161. * 
  162. *  This routine, with a given document, application, and a passed typelist will display the
  163. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  164. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  165. *  The routine returns the translation path information.
  166. * 
  167. *  Enter:    theDocument            FSSpec to document to open
  168. *             theApplication        FSSpec to application to open document
  169. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  170. *                                 you would like the documented translated to.  Order most perferred
  171. *                                 to least.
  172. * 
  173. *  Exit:    howToOpen            Translation method needed to open document
  174. *             howToTranslate        Translation specification
  175. *             returns                Any errors that might occur.
  176. */
  177. extern pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  178.  TWOWORDINLINE(0x7037, 0xABFC);
  179. /*****************************************************************************************
  180. * 
  181. *   TranslateFile
  182. * 
  183. *  This routine reads a file of one format and writes it to another file in another format. 
  184. *  The information on how to translated is generated by the routine CanDocBeOpened.
  185. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  186. *  The destination file must not exist.  It is created by this routine.  
  187. * 
  188. *  Enter:    sourceDocument            input file to translate
  189. *             destinationDocument        output file of translation
  190. *             howToTranslate            pointer to info on how to translate
  191. *  Exit:    returns                    noErr, badTranslationSpecErr 
  192. */
  193. extern pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  194.  TWOWORDINLINE(0x700C, 0xABFC);
  195. /*****************************************************************************************
  196. * 
  197. *   GetDocumentKindString
  198. * 
  199. *  This routine returns the string the Finder should show for the "kind" of a document
  200. *  in the GetInfo window and in the kind column of a list view.  
  201. * 
  202. *  Enter:    docVRefNum        The volume containing the document
  203. *             docType            The catInfo.fdType of the document
  204. *             docCreator        The catInfo.fdCreator of the document
  205. *             kindString        pointer to where to return the string
  206. * 
  207. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  208. *             returns            noErr, or afpItemNoFound if kind could not be determined
  209. */
  210. extern pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  211.  TWOWORDINLINE(0x7016, 0xABFC);
  212. /*****************************************************************************************
  213. * 
  214. *  GetTranslationExtensionName
  215. * 
  216. *  This routine returns the translation system name from a specified TranslationSpec
  217. * 
  218. *  Enter:    translationMethod    The translation path to get the translation name from
  219. * 
  220. *  Exit:    extensionName        The name of the translation system
  221. *             returns                Any errors that might occur
  222. */
  223. extern pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  224.  TWOWORDINLINE(0x7036, 0xABFC);
  225. /*****************************************************************************************
  226. * 
  227. *  GetScrapDataProcPtr
  228. * 
  229. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  230. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  231. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  232. *  with a list all the formats that you have available to be translated, and the length of each.
  233. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  234. *  the formats that 'fmts' list said was available.
  235. * 
  236. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  237. *             dataH                    Handle in which to put the requested data
  238. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  239. *             
  240. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  241. */
  242. typedef pascal OSErr (*GetScrapDataProcPtr)(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
  243.  
  244. #if GENERATINGCFM
  245. typedef UniversalProcPtr GetScrapDataUPP;
  246. #else
  247. typedef GetScrapDataProcPtr GetScrapDataUPP;
  248. #endif
  249.  
  250. enum {
  251.     uppGetScrapDataProcInfo = kPascalStackBased
  252.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  253.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ScrapType)))
  254.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))
  255.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(void*)))
  256. };
  257.  
  258. #if GENERATINGCFM
  259. #define NewGetScrapDataProc(userRoutine)        \
  260.         (GetScrapDataUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
  261. #else
  262. #define NewGetScrapDataProc(userRoutine)        \
  263.         ((GetScrapDataUPP) (userRoutine))
  264. #endif
  265.  
  266. #if GENERATINGCFM
  267. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  268.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
  269. #else
  270. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  271.         (*(userRoutine))((requestedFormat), (dataH), (srcDataGetterRefCon))
  272. #endif
  273.  
  274. typedef GetScrapDataUPP GetScrapData;
  275.  
  276. /*****************************************************************************************
  277. * 
  278. *  TranslateScrap
  279. * 
  280. *  This routine resizes the destination handle and fills it with data of the requested format.
  281. *  The data is generated by translated one or more source formats of data supplied by
  282. *  the procedure srcDataGetter.  
  283. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  284. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  285. * 
  286. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  287. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  288. *             destinationFormat            Format of data desired
  289. *             destinationData                Handle in which to store translated data
  290. *             
  291. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  292. */
  293. extern pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  294.  TWOWORDINLINE(0x700E, 0xABFC);
  295.  
  296. #if PRAGMA_IMPORT_SUPPORTED
  297. #pragma import off
  298. #endif
  299.  
  300. #if PRAGMA_ALIGN_SUPPORTED
  301. #pragma options align=reset
  302. #endif
  303.  
  304. #ifdef __cplusplus
  305. }
  306. #endif
  307.  
  308. #endif /* __TRANSLATION__ */
  309.